Weather
Use this plugin to show live weather conditions and a five-day forecast in your Q-SYS design. It pulls data from MET Norway, the Norwegian Meteorological Institute, under terms that allow commercial use — so there is no API key, account, or subscription to manage.
Conditions refresh automatically every ten minutes. An optional one-shot search against OpenStreetMap turns a place name or postal code into coordinates, so you rarely need to look up latitude and longitude by hand.
Compatibility
The plugin requires:
- A Q-SYS Core, or Designer emulation, with internet access.
- No special hardware, licence, or account. MET Norway and OpenStreetMap are both free to use under terms that allow commercial installs.
Quick Start
This takes about a minute, because the plugin already has somewhere to point.
- Drag the Weather plugin into your design.
- In the Properties pane, set Units to Metric or Imperial. See Properties.
- Press F5 to save the design to the Core and run it.
- Open the plugin and go to the Weather page. Conditions for Auckland, New Zealand appear within a few seconds — that's the default location, so you have live data before you've set anything up.
- To point it at your own site, go to Setup, type a place name into the search field, and press Search.
- Tap a result in the list, then press Use Selected Location. The plugin fetches weather for the new coordinates immediately.
Properties
Properties are set in the Designer Properties pane and read once when the design starts. Change them there rather than expecting a live update while running — a recompile or Save to Core picks up a change.
Units
Metric shows temperature in °C and speed in km/h. Imperial shows °F and mph. Applies to current conditions and the forecast. Default is Metric.
Debug Print
Controls how much diagnostic detail the plugin prints to the Q-SYS Lua console.
- Minimal — key milestones and errors only. Use this in production. Default.
- All — adds plain-language breadcrumbs: when a refresh starts, when it succeeds, when a search runs.
- Log — same as All, plus mirrors messages to the Core's system log file.
Controls
The plugin has three pages: Weather (current conditions), Forecast (five-day outlook), and Setup (location and appearance). A status pill in the top right of every page shows whether the plugin can currently reach the weather service.
Weather
The main operating page — put this one in front of an end user.
Current Conditions
The weather icon on the left is colored to match Icon Color from the Setup page, and updates automatically as conditions change. On the right: the current Temperature in large type, the Condition in words (for example Partly cloudy), the resolved location name, and when the reading was last updated.
Details
Feels (feels-like temperature), Humidity, Wind speed, Gust, wind direction as a compass point and degrees, and cloud cover.
Sun / Pressure
Rise and Set times for the current day, and barometric Pressure in hPa.
Refresh Now
Forces an immediate request, bypassing the ten-minute cache. Useful right after you change location, or if you just want to confirm the service is reachable.
Forecast
Five day-cards, each with an icon, the day name, condition, high and low temperature, and total precipitation.
The forecast is built from the same MET timeseries used for current conditions: each day's high and low are the maximum and minimum temperature reported for that day, and precipitation is the forecast total for the day. Precipitation is always shown in millimetres, even when Units is set to Imperial.
Setup
Everything needed to point the plugin at a site and make the icons match your design.
Location
Type Latitude and Longitude directly, and an Altitude in metres if you know it — MET's forecast is more accurate with altitude supplied, particularly in mountainous areas. Press Use / Refresh to apply a manual change immediately rather than waiting on the next scheduled poll. Resolved Location shows the location name currently in use.
Search
One operator-triggered request — not autocomplete. Type a city, venue, suburb, or postal code and press Search. See Finding a Location.
Status & Icon Color
The status readout echoes feedback from your last action — a completed search, an applied location, or an error. Icon Color is a hex value that recolors every weather icon in the plugin. See Customizing the Weather Icon.
How Refresh and Caching Work
The plugin polls MET Norway every ten minutes. It also honors ordinary HTTP caching: requests include an If-Modified-Since header, and when MET replies 304 Not Modified the plugin reuses the reading it already has rather than treating it as new data. If MET's response includes an Expires header further in the future than ten minutes, the plugin waits that long before asking again — but never less than ten minutes, regardless of what the header says.
If a request fails — MET is throttling (429), temporarily forbidden (403), or having a server-side problem (5xx) — the plugin keeps the last good reading on screen, sets Status to Compromised, and retries with a backoff: ten minutes, then twenty, then forty, doubling each time up to a two-hour ceiling. A single successful request resets the backoff back to ten minutes.
An invalid latitude or longitude (MET responds 422) sets Status to Fault and asks you to check Setup — this is the plugin telling you the coordinates themselves are the problem, not the network.
Note: Changing Latitude, Longitude, or Altitude on Setup clears the cached forecast immediately, so the next refresh always fetches fresh data for the new location rather than briefly showing a stale reading left over from the old one.
Finding a Location
The Setup page's search box turns a place name into coordinates using OpenStreetMap. Type a city, venue, suburb, or postal code and press Search — up to five matches come back in the results list. Nothing is sent until you press Search; it isn't autocomplete.
Tap a result, then press Use Selected Location. The plugin fills in Latitude and Longitude, updates Resolved Location, and immediately requests fresh weather for the new coordinates.
Customizing the Weather Icon
Every icon the plugin draws — current conditions and all five forecast days — is a single-color glyph rendered at runtime, not a fixed image. Icon Color on the Setup page is the hex color used to draw them, for example #28DC82 (the default mint green). Enter it with or without the leading #.
Changes apply on the fly to every icon on the Weather and Forecast pages — no refresh needed.
Note: An invalid entry (anything other than six hex digits) is rejected. The status readout explains why, and the field reverts to the last valid color automatically.
Control Pins
These pins appear on the plugin component in the design canvas, so you can wire them to other components, scripts, or a control system. In Q-SYS Designer's Control Pins panel they're grouped into folders — Status, Control, Current Conditions, and Forecast — matching the groups below. Every other control on the plugin's pages remains available to UCIs and external control by name, even though it isn't shown as a pin.
| Pin Name | Value | String | Purpose | Pins Available |
|---|---|---|---|---|
| Status | ||||
| Status | 0 – 5 | (text) | Weather service status. See note 2 below. | Output |
| Control | ||||
| RefreshNow | 0 1 |
false true |
Pulse to force an immediate refresh | Input |
| Current Conditions | ||||
| LocationName | - | (location name) | Resolved location currently in use | Output |
| Condition | - | (condition text) | Human-readable condition, for example "Partly cloudy" | Output |
| WeatherIconKey | - | (symbol code) | Raw MET symbol code behind the current icon, for example "partlycloudy_day" — useful for driving your own icon set from a third-party UCI | Output |
| Temperature | - | (formatted temperature) | Current temperature, formatted per the Units property | Output |
| WindSpeed | - | (formatted speed) | Current wind speed, formatted per the Units property | Output |
| WindDirection | - | (compass + degrees) | Wind direction, for example "NE 45 deg" | Output |
| WindGust | - | (formatted speed) | Current wind gust speed | Output |
| Sunrise | - | (HH:MM) | Sunrise time, local | Output |
| Sunset | - | (HH:MM) | Sunset time, local | Output |
| Forecast | ||||
| ForecastSummary n | - | (day summary) | One-line summary for forecast day n, for example "Mon: Partly cloudy, 12–18 C" | Output |